Node / mirrors / microReticulum_Firmware rns://f53941ecdb23472c4af67042474c7918/mirrors/microReticulum_Firmware

Mirrored from https://github.com/attermann/microReticulum_Firmware synced 9h ago

󰉖 Files • 󱌣 Work (0) • 󰋚 Commits (979) • 󰘬 Branches (11) • 󰓼 Tags (16) • 󰋑 Thanks (0) •  Stats

This firmware can be easily installed on devices in the same way as RNode using the new T383838fw-url switch to T383838rnodeconf which allows firmware images to be pulled from an alternate repository. RNS may need to be updated to the latest version to use this new switch.

The latest version of this firmware can be installed in the usual RNode way with the following command:

T282828

NOTE: If re-installing a new build of the same version installed previously, be sure to clear the rnodeconf cache first to force it to download the very latest.

T282828

By default this firmware will operate just like any other RNode firmware allowing it to be used as just a radio by RNS installed on an attached machine.

To enable T383838Transport Mode using the RNS embedded on the device, the device must be switched to TNC mode using a command like the following:

T282828

When in T383838Transport Mode, the device will display "TRANSPORT" across the top of the AirTime panel of the display to indicate that the embedded RNS is active and routing packets.

Note that at the present time, when in TNC mode this firmware does not operate like a regular RNode does when in TNC mode due to logging from the embedded RNS that is output on the serial port. This can clobber KISS communication from the attached machine so do not attempt to attach another RNS to the device while in this mode. On the plus side, there is extensive logging available on the serial port to observe the embedded RNS in action and to aid in troubleshooting.

Build environment is configured for use in VSCode and PlatformIO.

Building and uploading to hardware is simple through the VSCode PlatformIO IDE

• Install VSCode and PlatformIO

• Clone this repo

• Lanch PlatformIO and load repo

• In PlatformIO, select the environment for intended board

• Build, Upload, and Monitor to observe application logging

Uploading to devices requires access to the T383838rnodeconf utility included in the official Reticulum distribution to update the device firmware hash. Without this step the device will report invalid firmware and will fail to fully initialize.

Instructions for command line builds and packaging for firmware distribution.

• T383838-DHAS_RNS Used to enable the microReticulum RNS stack and transport node.

• T383838-DUDP_TRANSPORT Used to enable WiFi connection (when configured through T383838rnodeconf as an additional transport medium (currently hard-coded to use port 4242).

Clean all environments (boards):

T282828

Full Clean (including libdeps) all environments (boards):

T282828

Build a single environment (board):

T282828

Build and upload a single environment (board):

T282828

Build and package a single environment (board):

T282828

On erased EEPROM, the Heltec Wireless Tracker V2 enables BLE and explicitly

disables Wi-Fi; later user choices are preserved. Radio parameters remain unset

until a user selects region-appropriate values.

Build all environments (boards):

T282828

Build and package all environments (boards):

T282828

Write version info:

python release_hashes.py > Release/release.json

New firmware release procedure:

1. Ensure that microReticulum repo is updated for build (and package versioning is incremented if changed)

2. Shutdown microReticulum_Firmware project in IDE (if open)

3. Clean build directory

T282828

4. Clean release directory

T282828

5. Build new releases

T282828

6. Upload all files (except README.md and esptool) to github release

This firmware adds a structured Provisioning subsystem on top of the legacy RNode KISS protocol and a single-page web app — the RNode Console — that drives it. Together they replace ad-hoc T383838rnodeconf invocations for day-to-day setup and give the same view of a node whether you are sitting next to it with a USB cable or several LoRa hops away.

For an end-user walkthrough (including remote management and per-transport caveats) see docs/Provisioning.md.

The Provisioning subsystem is a typed, namespaced configuration engine running inside the embedded microReticulum stack. Each settable item (LoRa interface mode, NomadNet site name, KISS-framed logging, etc.) is declared as a field with a type, flags (T383838LIVE_APPLY, T383838REBOOT_REQUIRED, T383838READ_ONLY, T383838WRITE_ONLY, T383838SECRET), and a setter/getter. Live metrics (radio link, channel utilisation, RNS destination hashes, WiFi info) are surfaced through the same engine as read-only fields. A draft/commit model — T383838SetState → T383838Commit (or T383838Discard) — means changes are staged before they touch the device, with reboot-required changes flagged separately. Persisted state is stored in MsgPack files alongside Reticulum's path table. See T383838Provisioning.h / T383838Provisioning.cpp and the T383838RNS_USE_PROVISIONING / T383838RNS_ENABLE_REMOTE_PROVISIONING build flags for the wire protocol.

Crucially, the same wire protocol is available locally (KISS-framed over USB / BLE / WiFi WebSocket) and remotely (carried over a Reticulum Link to the node's T383838rnstransport.remote.management destination), so the node can be configured from anywhere it can be reached on the mesh.

The RNode Console is a single-page web app (sources in T383838webconsole/index.html, packaged delivery artifact in T383838Release/console.html) that speaks the Provisioning protocol directly from the browser. It runs entirely client-side — no backend other than the node itself. Open T383838Release/console.html from disk (or host it from any static web server) and pick a transport:

Both share T383838lib_deps; Portduino's T383838#ifdef __linux__ guards pick the simulated vs real backend at compile time.

• Same firmware, same protocols. The native build is the same T383838RNode_Firmware.ino codebase as the embedded targets; the Provisioning subsystem, microReticulum stack, NomadNet stats pages, and legacy KISS opcodes all behave identically.

• T383838rnoded.conf runtime configuration. Pin map, GPIO chip, SPI device + speed, LoRa modem family + parameters, TCXO voltage, RF-switch behaviour, auxiliary "radio enable" pins, and TX-failure recovery are all read at startup from a key=value text file. See T383838rnoded.example.conf for the full schema. Overrides: T383838--config PATH / T383838-c PATH on the command line, or T383838$MR_CONFIG. The data directory (where Reticulum's path store, the EEPROM image, etc. live) is set by T383838data_dir in the config or T383838$MR_DATA_DIR.

• Self-provisioning EEPROM. On first boot, T383838native/PinMap.cpp::seed_eeprom_if_unprovisioned() seeds the EEPROM image so T383838rnodeconf is not needed to bring the daemon up. The rnodeconf-style MD5 firmware-image check is bypassed (T383838-DDISABLE_FIRMWARE_CHECKSUM).

• KISS over localhost TCP. The embedded USB-serial KISS channel is replaced by a TCP server (default T383838127.0.0.1:7633). Tools that would normally open T383838/dev/ttyACM0 (rnodeconf, RNS T383838KISSInterface) connect to that socket instead. Loopback by default; T383838kiss_tcp_public = true in T383838rnoded.conf opts into binding T3838380.0.0.0.

• KISS over WebSocket on port 8080 so the RNode Console can drive the daemon from a browser. Same loopback-by-default model — T383838kiss_ws_public = true opens it up.

• Forced TNC mode. The native daemon boots with T383838op_mode = MODE_TNC so the Reticulum Transport runs in routing mode without needing a host to flip the bit.

• Re-exec on reboot. A T383838Reboot from the Console (or any other source) re-execs the daemon in place — the cwd is captured at launch so the child resolves T383838rnoded.conf against the same directory.

• Systemd-ready. A reference unit file is included (T383838rnoded.example.service) — drop a copy into T383838/etc/systemd/system/ and adapt the user/working directory.

• macOS (Apple Silicon / Intel) via T383838native-macos. Builds on macOS only; needs T383838argp-standalone (T383838brew install argp-standalone) because Apple's libc lacks T383838argp.h. The simulated SPI / GPIO backend means no LoRa traffic actually flows, but everything else — provisioning, KISS over TCP + WebSocket, the web console, microReticulum's path store — runs end-to-end.

• Linux via T383838native. Tested on Raspberry Pi (Bookworm), FemtoFox, and LuckFox Pico (Mini / Plus). Any Linux host with T383838libgpiod and T383838/dev/spidev will work as long as a supported SX12xx modem is wired to it. Cross-build environments for Debian Bookworm and Ubuntu Jammy on amd64 / arm64 / armhf are provided under T383838docker/.

Common HATs / wirings are documented in T383838rnoded.example.conf, including RAK6421 + RAK13302 (SX1262 with PA), the Waveshare SX126x LoRa HAT, and LuckFox Pico + RFM95x (SX1276).

• [x] Extend KISS interface to support config/control of the integrated microReticulum stack

• [x] Add interface for easy customization of firmware

• [ ] Add power management and sleep states to extend battery runtime

• [x] Add build targets for NRF52 boards

Please open an Issue if you have trouble building or using the firmware or daemon, and feel free to start a new Discussion for anything else.

Contributions to microReticulum_Firmware are welcome and appreciated.

Before opening an issue or submitting a pull request, please read the project's CONTRIBUTING.md guide. It describes the expectations for bug reports, feature requests, coding standards, testing, and pull requests.

In particular, contributors are asked to:

• Clearly identify the problem being solved before describing the proposed solution.

• Keep pull requests focused on a single logical concern.

• Test changes thoroughly, including on all affected platforms when modifying shared code.

• Update documentation when introducing user-visible changes.

Following these guidelines helps streamline reviews, improve software quality, and make it easier to integrate contributions.